home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / utility / 533 / kwic / read_me.txt < prev    next >
Text File  |  1991-07-02  |  11KB  |  224 lines
  1.         
  2.                      Documentation for KWIC.PRG
  3.  
  4.         Key Words in Context listings have been in use for 
  5.         several years by technical libraries.  
  6.         Essentially, They  provide an abstracting service 
  7.         where no provider of such a service exists.  Key 
  8.         words are extracted from the title of a book or 
  9.         journal article, sorted, and the entire title is 
  10.         printed in its' original context; that is, the 
  11.         full title of the work.  A key word is simply any 
  12.         word that is not on a list of words to be 
  13.         excluded. Excluded words include the articles and 
  14.         most prepositions and conjunctions.  Thus, a 
  15.         person doing research on migraine headaches looks 
  16.         under 'migraine', 'headache', any other synonyms 
  17.         he knows and under the drugs commonly prescribed 
  18.         for this terrible malady. Some of the titles will 
  19.         appear more than once during his search, of 
  20.         course, but once he finishes he knows that he has 
  21.         exhausted the information content of the set of 
  22.         titles.  The program can be used directly from the 
  23.         monitor instead of a hard copy, but the listing 
  24.         offers portability.  Also I find the presence of 
  25.         the computer a distraction, one gets fascinated 
  26.         with the research tool instead of the problem 
  27.         being researched.  (How many ex chemists, 
  28.         biologists, astronomers, ...., are now computer 
  29.         programmers?)
  30.  
  31.         
  32.                          Getting started
  33.         If you have a reasonably standard printer that is 
  34.         powered up and ready  to print, you can 
  35.         demonstrate the program simply by executing it and 
  36.         giving it the default response (a carriage return) 
  37.         every time a question is asked.  Sample files are 
  38.         included to be used as a base for a built in 
  39.         demonstration.  
  40.         
  41.                       How I use this program
  42.                 I collect cookbooks.  I have no data base 
  43.         program to assist me.  There are several sub 
  44.         categories to the collection. That is paper backs, 
  45.         unusually prolific authors, books that are 
  46.         encyclopedic in nature,  books too big for 
  47.         ordinary shelves, and so on.  The sample file 
  48.         included here is one of the sub collections.  The 
  49.         main file of rather ordinary hard bound books is 
  50.         too large to include in an upload. The main file 
  51.         starts with the book title in column 1 and has the 
  52.         authors' name starting in column 40. (Note that 
  53.         the sample file included here is a _sub_ 
  54.         collection and does not have the author's name 
  55.         field.)  The file is sorted by author name and 
  56.         the books are shelved in that order too.  Sorting 
  57.         is done with a public domain sort program.  Each 
  58.         book is represented by a one line entry.  This is 
  59.         necessary because the sort program I use demands a 
  60.         _consistent_ record length.  That is, a record is 
  61.         zero or more characters followed by a CR and LF.  
  62.         
  63.         To make a KWIC listing, I specify the particular 
  64.         file of interest when 'input file' is called for.  
  65.         I often make composite listings including several 
  66.         sub-categories.  To make a composite file, I find 
  67.         the Public Domain program PCOMMA (aka PCOMMAND), 
  68.         which emulates PC-DOS invaluable.  I have several 
  69.         .BATch files which, when run, join up the individual 
  70.         files in various ways and produce the desired 
  71.         composite file. 
  72.         
  73.         When the file of 'bad words' is called for I use a 
  74.         personalized file.  Some words are used so often 
  75.         _within_ a specialty that they become simply 
  76.         'noise words'.  In cookbooks, such words as 
  77.         'cook', book' 'cookbook', and 'recipe' come up so 
  78.         often as to be meaningless. When the program asks 
  79.         for columns to be ignored, I specify column 39.  
  80.         This means that the authors' name is not a 
  81.         keyword. After all, I already have a listing 
  82.         sorted by authors' name.  I also sometimes have 
  83.         notes beyond column 39 and I want them ignored 
  84.         too, as far as key words are concerned. 
  85.         
  86.         When KWIC asks for the leftmost column for the 
  87.         keyword, I specify column 60.  I then specify an 
  88.         Epson printer, with printing to be 137 columns 
  89.         wide.  So I end up with a hard copy with key words 
  90.         nicely aligned on column 60 and the authors' name 
  91.         is on the same line (but not aligned properly, 
  92.         unfortunately) so I can find the book physically 
  93.         without referring to another index.  That's how I 
  94.         use it. Now on to the general nature of the beast.
  95.  
  96.         
  97.                           The Input file
  98.         The input file is prepared with your favorite text 
  99.         editor or a word processor in ASCII mode.  It is a 
  100.         list of book titles, journal articles, or any 
  101.         analogous item.  An entry normally starts in 
  102.         column 1 and can be as long as desired, within 
  103.         reason.  The program will work best however, with 
  104.         relatively short entries, say 80 characters or 
  105.         less. Normal practice will result in most key 
  106.         words having the initial letter in upper case.  
  107.         The program will find them regardless of 
  108.         upper/lower problems.  But after they are found 
  109.         they are sorted following the collating order of 
  110.         ASCII.  That means that 'a' follows 'Z'.  Numbers 
  111.         will be found as key words too.  Sorting puts all 
  112.         digits ahead of all letters.  Blank lines in the 
  113.         input file will be ignored.  
  114.         
  115.         
  116.         
  117.                     The bad word file
  118.         
  119.         You can make your own personalized bad word file 
  120.         by modifying the file included with the .ARC.  It 
  121.         is a simple text file, too.  The word must start 
  122.         in column 1 and be followed _immediately_ by 
  123.         [Return].  That is, 'apple' is not the same as 
  124.         'apple '.  These words should all be lower case.  
  125.         You can enter the words in any order that occurs 
  126.         to you; the program will automatically do a simple  
  127.         resort of the bad word file every time it runs.    
  128.         You can have as many bad word files as you wish.  
  129.         The file included is specialized for cookbooks.  
  130.         About the first 80 entries would apply to any English 
  131.         title, simply remove the specialized words and 
  132.         replace them with your own set.  
  133.         
  134.         
  135.                           Program Output
  136.         After the program has run and extracted all the 
  137.         key words and sorted them, it is ready to provide 
  138.         output.  Since the program may run for several 
  139.         minutes, it allows you to get several 
  140.         outputs from a single run of the program.  The 
  141.         monitor choice is mostly offered as a preview to 
  142.         get an idea of whether things turned out OK.  
  143.         Since it is limited to 80 columns width, it is not 
  144.         very effective for long records.  The basic output 
  145.         will often be an Epson printer with the 137 
  146.         column line choice.  This permits you to align the 
  147.         key words at, say column 60 and get a nice looking 
  148.         output with reasonably sized titles.
  149.         
  150.                        Non-Epson printers
  151.          If you have a non Epson printer, there are two 
  152.         alternatives. The first alternative is to set up 
  153.         the printer to produce some kind of compressed 
  154.         printing _before_ you run KWIC.  KWIC will not 
  155.         send anything except data to the printer if you 
  156.         specify non Epson.  You can also use this approach 
  157.         if you want more than 137 columns on an Epson 
  158.         printer, the printer can easily go to 160 columns 
  159.         and can even be pushed to exceed that.
  160.         
  161.         The other alternative is to specify output to a 
  162.         file.  This will be an ordinary ASCII file which 
  163.         you can read into a text editor, perhaps do 
  164.         further editing, and output the same way you would 
  165.         any other text file.  One word about writing to a 
  166.         file.  The program uses the default Personal 
  167.         Pascal text file write and it performs an 
  168.         incredible amount of slow activity on the disk.  
  169.         If you have a nervous temperament, as I do, and 
  170.         you see hundreds of writes to your disk, you may 
  171.         get very tense.  The program works fine, but if 
  172.         this bothers you, write to a blank floppy disk 
  173.         (making things even slower!) and then copy that 
  174.         file to your hard disk.  I could have speeded this 
  175.         write up, but considering the nature of the 
  176.         program, it just didn't seem worth the effort.  
  177.         Note also, that the file produced can easily be quite 
  178.         large, one that I commonly produce is in excess of
  179.         200,000 bytes.
  180.  
  181.         
  182.                           Loose ends
  183.         The program allows input files to be up to 110,000 
  184.         bytes long and to have up to 8,000 key words.  Normal 
  185.         printing would produce up to a 140 page listing.  
  186.         One of these sizes may be too small for your 
  187.         situation, or the ratio (the number of key words 
  188.         per title) may be wrong for you.  These numbers 
  189.         were chosen to allow the program to run in a 
  190.         system that has about 250K bytes of free RAM.  If 
  191.         you want a customized version, send me E-Mail on 
  192.         GEnie and I can probably make a special version 
  193.         for you to fit your needs.
  194.  
  195.         The program doesn't care what file names or file 
  196.         name extensions you use; the names provided on the 
  197.         file selectors are merely suggestions.
  198.  
  199.         For those interested in Pascal, note that the sort 
  200.         program included can be used as a debugged 
  201.         Quicksort.  To customize it, simply change the 
  202.         type declarations and the SWAP procedure.  The 
  203.         base routine is fast, it is so slow as used here 
  204.         because it uses Pascal string logic to copare two 
  205.         11 character strings.  This could easily be 
  206.         speeded up, but considering the nature of this 
  207.         program, it didn't seem worthwhile.  The procedure 
  208.         that reads a file of arbitrary length into an 
  209.         ARRAY of characters might also be useful, it seems 
  210.         that so many programs start out (or should start 
  211.         out) by doing just that.
  212.           
  213.         This program may be freely copied, uploaded, and 
  214.         propogated by any suitable means as long as the
  215.         content passed on includes _all_ the files contained 
  216.         in the original ARChive.   Additionally, the name 
  217.         should remain KWIC.ARC unless the target system
  218.         already has that name in use.  Placed in public domain 
  219.         July 1991.
  220.         
  221.                          Merlin Hanson
  222.                     GEnie address: M.L.HANSON
  223.  
  224.